---
title: Protocol Upgrades
description: The Sui protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. The upgrade process ensures all clients use the same source.
keywords: [ protocol upgrades, framework upgrades, protocol config, feature flags, validator upgrades, protocol version ]
---

The Sui protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. This functionality is added as new code released to validator operators as part of regular software releases.

As [consensus](/concepts/sui-architecture/consensus.mdx) requires that all validators agree on the results of executing each transaction, how is code released that changes transaction execution, given that operators cannot all upgrade at the same instant? Further, how is it ensured that all transaction history can be replayed even after functionality has changed?

To solve this, Sui uses a process called _protocol upgrades_.

## Protocol upgrade process

The process for protocol upgrades includes the following steps:

1. A developer codes the new feature but restricts access to it with a feature flag, a boolean configuration variable initially set to false.

1. The value of the feature flag is retrieved from a struct called `ProtocolConfig`.

1. The developer creates a new version of the `ProtocolConfig` struct where the feature flag is set to true.

1. A new release of the Sui validator software is built and released to validator and full node operators.

1. When the validator process starts, it continues to use the previous version of `ProtocolConfig` (flag set to false). All validators behave identically regardless of whether they have the new software.

1. As validators are upgraded, they signal to the validator committee that they are prepared to switch to the new version of the configuration (flag enabled).

1. If 2/3 or more of validators vote to switch to the new protocol version, the new version takes effect at the beginning of the next epoch.

1. The new feature becomes active.

Full node operators follow a similar process but do not participate in voting. They follow the actions recorded by validators.

When validators switch to a new protocol version, they record the new version number in the special end-of-epoch transaction. Full nodes execute this transaction as they replay the chain history, allowing them to switch to the new protocol version at the correct time.

## Framework upgrades

Not all new Sui functionality comes from validator code changes. Developers also extend the Sui framework. For example, they might add new native functions to expose functionality to smart contracts. The process for framework updates is similar to protocol upgrades.

Instead of feature flags, Sui objects coordinate framework changes. The Sui framework is a special object with ID `0x2`. The Move source code for the framework is built into the validator binary.

If a validator notices that its built-in framework differs from the framework in object `0x2`, it signals to other validators that it wants to upgrade the framework to a new version. As with `ProtocolConfig`, if 2/3 or more of validators agree, the new framework object is written at the end of the current epoch. Transactions executed in the new epoch then use the new version of the framework.

## Related links

<RelatedLink to="/concepts/sui-architecture/consensus.mdx" />